package com.school.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.school.common.PageResult;
import com.school.entity.Student;

import java.util.List;
import java.util.Map;

/**
 * 学生信息服务接口
 * 
 * @author School Development Team
 * @version 1.0.0
 * @since 2024
 */
public interface StudentService extends IService<Student> {

    /**
     * 分页查询学生信息
     * 
     * @param current 当前页码
     * @param size 每页大小
     * @param params 查询参数
     * @return 学生信息分页结果
     */
    PageResult<Student> getStudentPage(Long current, Long size, Map<String, Object> params);

    /**
     * 根据学生ID查询学生详细信息
     * 
     * @param studentId 学生ID
     * @return 学生详细信息
     */
    Student getStudentDetail(String studentId);

    /**
     * 新增学生
     * 
     * @param student 学生信息
     * @return 是否成功
     */
    boolean addStudent(Student student);

    /**
     * 更新学生信息
     * 
     * @param student 学生信息
     * @return 是否成功
     */
    boolean updateStudent(Student student);

    /**
     * 删除学生
     * 
     * @param studentId 学生ID
     * @return 是否成功
     */
    boolean deleteStudent(String studentId);

    /**
     * 批量删除学生
     * 
     * @param studentIds 学生ID列表
     * @return 是否成功
     */
    boolean batchDeleteStudents(List<String> studentIds);

    /**
     * 根据班级ID查询学生列表
     * 
     * @param classId 班级ID
     * @return 学生列表
     */
    List<Student> getStudentsByClassId(String classId);

    /**
     * 根据身份证号查询学生
     * 
     * @param idCard 身份证号
     * @return 学生信息
     */
    Student getStudentByIdCard(String idCard);

    /**
     * 检查身份证号是否已存在
     * 
     * @param idCard 身份证号
     * @param excludeStudentId 排除的学生ID（用于更新时检查）
     * @return 是否存在
     */
    boolean isIdCardExists(String idCard, String excludeStudentId);

    /**
     * 转班操作
     * 
     * @param studentId 学生ID
     * @param newClassId 新班级ID
     * @return 是否成功
     */
    boolean transferClass(String studentId, String newClassId);

    /**
     * 批量转班
     * 
     * @param studentIds 学生ID列表
     * @param newClassId 新班级ID
     * @return 是否成功
     */
    boolean batchTransferClass(List<String> studentIds, String newClassId);

    /**
     * 更新学生状态
     * 
     * @param studentId 学生ID
     * @param status 新状态
     * @return 是否成功
     */
    boolean updateStudentStatus(String studentId, String status);

    /**
     * 批量更新学生状态
     * 
     * @param studentIds 学生ID列表
     * @param status 新状态
     * @return 是否成功
     */
    boolean batchUpdateStudentStatus(List<String> studentIds, String status);

    /**
     * 统计各班级学生数量
     * 
     * @return 班级学生数量统计
     */
    List<Map<String, Object>> getStudentCountByClass();

    /**
     * 统计各年级学生数量
     * 
     * @return 年级学生数量统计
     */
    List<Map<String, Object>> getStudentCountByGrade();

    /**
     * 统计学生状态分布
     * 
     * @return 学生状态统计
     */
    List<Map<String, Object>> getStudentCountByStatus();

    /**
     * 根据监护人电话查询学生列表
     * 
     * @param guardianPhone 监护人电话
     * @return 学生列表
     */
    List<Student> getStudentsByGuardianPhone(String guardianPhone);

    /**
     * 查询即将毕业的学生
     * 
     * @param graduationYear 毕业年份
     * @return 即将毕业的学生列表
     */
    List<Student> getGraduatingStudents(Integer graduationYear);

    /**
     * 查询新入学的学生
     * 
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 新入学学生列表
     */
    List<Student> getNewEnrollmentStudents(String startDate, String endDate);

    /**
     * 查询未分班的学生
     * 
     * @return 未分班学生列表
     */
    List<Student> getStudentsWithoutClass();

    /**
     * 根据年龄范围查询学生
     * 
     * @param minAge 最小年龄
     * @param maxAge 最大年龄
     * @return 学生列表
     */
    List<Student> getStudentsByAgeRange(Integer minAge, Integer maxAge);

    /**
     * 获取学生总数
     * 
     * @return 学生总数
     */
    Long getTotalStudentCount();

    /**
     * 获取活跃学生数
     * 
     * @return 活跃学生数
     */
    Long getActiveStudentCount();

    /**
     * 模糊查询学生
     * 
     * @param keyword 关键词
     * @return 学生列表
     */
    List<Student> searchStudents(String keyword);

    /**
     * 导入学生数据
     * 
     * @param students 学生列表
     * @return 导入结果
     */
    Map<String, Object> importStudents(List<Student> students);

    /**
     * 导出学生数据
     * 
     * @param params 查询参数
     * @return 学生列表
     */
    List<Student> exportStudents(Map<String, Object> params);

    /**
     * 生成学生ID
     * 
     * @param classId 班级ID
     * @param enrollmentYear 入学年份
     * @return 学生ID
     */
    String generateStudentId(String classId, Integer enrollmentYear);

    /**
     * 验证学生信息
     * 
     * @param student 学生信息
     * @return 验证结果
     */
    Map<String, String> validateStudent(Student student);
}